memoize-one
A memoization library that only caches the result of the most recent arguments.
Also async version.
![Downloads per month](https://img.shields.io/npm/dm/memoize-one.svg)
Rationale
Unlike other memoization libraries, memoize-one
only remembers the latest arguments and result. No need to worry about cache busting mechanisms such as maxAge
, maxSize
, exclusions
and so on, which can be prone to memory leaks. memoize-one
simply remembers the last arguments, and if the function is next called with the same arguments then it returns the previous result.
Usage
import memoizeOne from 'memoize-one';
const add = (a, b) => a + b;
const memoizedAdd = memoizeOne(add);
memoizedAdd(1, 2);
memoizedAdd(1, 2);
memoizedAdd(2, 3);
memoizedAdd(2, 3);
memoizedAdd(1, 2);
Installation
yarn add memoize-one
npm install memoize-one --save
Function argument equality
By default, we apply our own fast and naive equality function to determine whether the arguments provided to your function are equal. You can see the full code here: are-inputs-equal.ts.
(By default) function arguments are considered equal if:
- there is same amount of arguments
- each new argument has strict equality (
===
) with the previous argument - [special case] if two arguments are not
===
and they are both NaN
then the two arguments are treated as equal
What this looks like in practice:
import memoizeOne from 'memoize-one';
const add = (...args = []) =>
args.reduce((current, value) => {
return current + value;
}, 0);
const memoizedAdd = memoizeOne(add);
- there is same amount of arguments
memoizedAdd(1, 2);
memoizedAdd(1, 2, 3);
- new arguments have strict equality (
===
) with the previous argument
memoizedAdd(1, 2);
memoizedAdd(1, 2);
memoizedAdd(1, 3);
memoizedAdd(3, 1);
- [special case] if the arguments are not
===
and they are both NaN
then the argument is treated as equal
memoizedAdd(NaN);
memoizedAdd(NaN);
Custom equality function
You can also pass in a custom function for checking the equality of two sets of arguments
const memoized = memoizeOne(fn, isEqual);
The equality function needs to conform to this type
:
type EqualityFn = (newArgs: any[], lastArgs: any[]) => boolean;
import { EqualityFn } from 'memoize-one';
import type { EqualityFn } from 'memoize-one';
An equality function should return true
if the arguments are equal. If true
is returned then the wrapped function will not be called.
A custom equality function needs to compare Arrays
. The newArgs
array will be a new reference every time so a simple newArgs === lastArgs
will always return false
.
Equality functions are not called if the this
context of the function has changed (see below).
Here is an example that uses a dequal deep equal equality check
dequal
correctly handles deep comparing two arrays
import memoizeOne from 'memoize-one';
import { dequal as isDeepEqual } from 'dequal';
const identity = (x) => x;
const shallowMemoized = memoizeOne(identity);
const deepMemoized = memoizeOne(identity, isDeepEqual);
const result1 = shallowMemoized({ foo: 'bar' });
const result2 = shallowMemoized({ foo: 'bar' });
result1 === result2;
const result3 = deepMemoized({ foo: 'bar' });
const result4 = deepMemoized({ foo: 'bar' });
result3 === result4;
this
memoize-one
correctly respects this
control
This library takes special care to maintain, and allow control over the the this
context for both the original function being memoized as well as the returned memoized function. Both the original function and the memoized function's this
context respect all the this
controlling techniques:
- new bindings (
new
) - explicit binding (
call
, apply
, bind
); - implicit binding (call site:
obj.foo()
); - default binding (
window
or undefined
in strict mode
); - fat arrow binding (binding to lexical
this
) - ignored this (pass
null
as this
to explicit binding)
Changes to this
is considered an argument change
Changes to the running context (this
) of a function can result in the function returning a different value even though its arguments have stayed the same:
function getA() {
return this.a;
}
const temp1 = {
a: 20,
};
const temp2 = {
a: 30,
};
getA.call(temp1);
getA.call(temp2);
Therefore, in order to prevent against unexpected results, memoize-one
takes into account the current execution context (this
) of the memoized function. If this
is different to the previous invocation then it is considered a change in argument. further discussion.
Generally this will be of no impact if you are not explicity controlling the this
context of functions you want to memoize with explicit binding or implicit binding. memoize-One
will detect when you are manipulating this
and will then consider the this
context as an argument. If this
changes, it will re-execute the original function even if the arguments have not changed.
When your result function throw
s
There is no caching when your result function throws
If your result function throw
s then the memoized function will also throw. The throw will not break the memoized functions existing argument cache. It means the memoized function will pretend like it was never called with arguments that made it throw
.
const canThrow = (name: string) => {
console.log('called');
if (name === 'throw') {
throw new Error(name);
}
return { name };
};
const memoized = memoizeOne(canThrow);
const value1 = memoized('Alex');
const value2 = memoized('Alex');
console.log(value1 === value2);
try {
memoized('throw');
} catch (e) {
firstError = e;
}
try {
memoized('throw');
} catch (e) {
secondError = e;
}
console.log(firstError !== secondError);
const value3 = memoized('Alex');
console.log(value1 === value3);
Performance 🚀
Tiny
memoize-one
is super lightweight at
minified and
gzipped. (1KB
= 1,024 Bytes
)
Extremely fast
memoize-one
performs better or on par with than other popular memoization libraries for the purpose of remembering the latest invocation.
Results
The comparisons are not exhaustive and are primarily to show that memoize-one
accomplishes remembering the latest invocation really fast. The benchmarks do not take into account the differences in feature sets, library sizes, parse time, and so on.
Code health 👍
- Tested with all built in JavaScript types.
- 100% code coverage
- Continuous integration to run tests and type checks.
- Written in
Typescript
- Correct typing for
Typescript
and flow
type systems - No dependencies